home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / debuging.arc / XRAY.DOC < prev   
Text File  |  1988-04-11  |  11KB  |  239 lines

  1. XRAY.COM, the PC Background Monitor
  2.  
  3.     YARP: Yet Another (DOS) Resident Program.  So what makes this one
  4.     special?
  5.  
  6.     What is XRAY?
  7.  
  8.     XRAY is a tool that allows you to monitor areas of your computer's
  9.     memory while other programs are running.  These other programs can
  10.     be COMMAND.COM, for those interested in some aspect of that program;
  11.     your own resident programs; or some .COM or .EXE application.  XRAY
  12.     gives you, on a real-time basis, the ability to watch memory variables
  13.     or your stack change dynamically.
  14.  
  15.  
  16.  
  17.     How would I best use XRAY?
  18.  
  19.     I typically use XRAY in combination with DEBUG.COM.  Probably the
  20.     the most difficult thing to find with DEBUG when tracing through code
  21.     is which subroutines are corrupting the stack.  To find this, one must
  22.     dump the stack, inspect the values carefully or make a hardcopy, set
  23.     the desired breakpoint, and then redump the stack and compare.  This
  24.     becomes extremely time consuming if your program is highly stack inten-
  25.     sive as are C or Pascal programs.  XRAY allows you to watch the stack
  26.     as you trace and break.  Armed with a MAP, DEBUG, and XRAY, the culprit
  27.     module can be quickly found and fixed.
  28.  
  29.     Another use for XRAY is debuging resident programs.  If you have a
  30.     program which is intended to be used under some other applications,
  31.     XRAY will let you watch its variables and the like change as you test
  32.     it.  For instance, the original version of XRAY simply loaded,
  33.     printed its SEGMENT:OFFSET value and terminated but remained resident.
  34.     To invoke the window or set the display address of the window a second
  35.     program had to be run.  After monitoring the keyboard data areas
  36.     and seeing how Shift, Alt, Cntl, etc. keys were being handled, I imp-
  37.     lemented the mechanism for invoking XRAY that it has now: Alt/Left-Shft.
  38.  
  39.     I also had some stack-size problems with XRAY originally and used XRAY
  40.     to find these problems by watching the stacks overflow.  Without using
  41.     XRAY it would have been a trial-and-error guessing game.  With XRAY
  42.     it was a quick fix!
  43.  
  44.     XRAY's main concept is to monitor memory while the system is running,
  45.     and this is where XRAY's use is unparalleled.  Whether you are writing
  46.     a multitask dispatcher, a resident keyboard handler/enhancer, or a COBOL
  47.     mailorder program, XRAY can help you find problems easily, where in the
  48.     past a vigorous trace-n-break-n-dump session with DEBUG.COM, or some
  49.     similar debugger, was required.  Once you get the hang of it, XRAY will
  50.     prove to be a valuable addition to your arsenal.
  51.  
  52.     Why did you write this program?
  53.  
  54.     I wrote XRAY because I use DEBUG.COM daily and needed a little more
  55.     than DEBUG had to offer.  I do have several other debuggers at my
  56.     disposal, and no doubt they have some great features, but I have yet
  57.     to find one with this window feature.  I was tempted to write a full
  58.     debugger in the beginning, but decided against it since DEBUG really
  59.     does quite nicely under most circumstances: it comes with DOS, it has
  60.     simple commands, and it will do most everything you need a debugger to
  61.     do.  Because of that, I decided to simply write something to (where's
  62.     the) "beef" it up a tad:  XRAY.  After XRAY was written, it turned out
  63.     to have more uses than I originally planned.  Fine.  In fact, great.
  64.     Still, my original goal was accomplished.
  65.  
  66.  
  67.     Are there any outstanding bugs that you know of?
  68.  
  69.     XRAY has been tested on an IBM PC, PC/XT, PC/AT, Zenith HS-150, Compaq,
  70.     IT&T, and the MAD computers.  So far, so good.  The only problem I've
  71.     encountered is with the IBM CGA (Color Graphics Adapter).  With this
  72.     piece of hardware XRAY causes the screen to flicker and "snow."  This
  73.     is because XRAY accesses the video regen buffer directly and does not
  74.     disable the CRT or check for vertical retrace from the 6845 CRT chip.
  75.     For those of you who use this card, ever notice the "flicker" you get
  76.     when text is scrolling off the screen?  This comes from the ROM video
  77.     support which disables (i.e. turns off) the monitor while it accesses
  78.     the video regen memory.  If this were done in XRAY--and I did try it,
  79.     incidently--the screen would flash badly constantly, and you'd have a
  80.     headache quicker than you could say XRAY.  XRAY still functions
  81.     ok, just has the flickering.  Wish I could change it.  If someone knows
  82.     how let me know.
  83.  
  84.     How do I bring up the XRAY window?
  85.  
  86.     Press down the Alt and Left Shift keys simultaneously.
  87.  
  88.  
  89.     Could you explain each of the features of XRAY?
  90.  
  91.     Gladly.
  92.  
  93.     1.) Sleep/Wake  Up
  94.  
  95.         This is the mechanism used to invoke XRAY's display window.
  96.         After XRAY is first loaded the default is Sleep.  To Wake Up
  97.         XRAY you press Alt+Left-Shift whichs brings up the main menu,
  98.         position the selection bar over Sleep, and hit Return.   Next
  99.         press Esc to put the menu away and start the XRAY display.  To
  100.         put the window away bring the menu up as before, position the
  101.         selection bar over Wake  Up, press Return, and then presss Esc.
  102.         The XRAY window will go away and the text underneath it will be
  103.         restored.
  104.  
  105.     2.) Set Scroll
  106.  
  107.         This feature allows you to scan a segment of memory.  The
  108.         default setting is None--no scrolling.  To change this bring
  109.         up the XRAY main menu, position the selection bar over Set
  110.         Scroll, and press Return.  This will bring up a second, smaller
  111.         menu with these choices:
  112.                     None
  113.                     Slow
  114.                     Fast
  115.  
  116.         None: leave the window focused on the same area of memory.
  117.         Slow: display 18 bytes (one line) farther in memory each second.
  118.         Fast: display 288 bytes (18 lines) farther in memory per second.
  119.  
  120.         This allows you to seach for a given location to display, or
  121.         to constantly circulate through a segment of memory.  When the
  122.         top of the memory segment is reached (hex FFFF) the display will
  123.         circulate back to 0.
  124.  
  125.         To select, position the selection bar and press Return.  Esc can
  126.         be pressed alone to exit the menu without changing the current
  127.         selection.
  128.  
  129.         Hint:  to use scroll to search for the area you need, turn on
  130.         Slow or Fast and keep your fingers near Alt and Left-Shift.
  131.         When you see the desired memory area bring up the XRAY window
  132.         and turn off scrolling.
  133.  
  134.     3.) Window  Size
  135.  
  136.         This feature allows you to change the size of the XRAY window
  137.         from 1 to 20 lines of display.  Simply position the selection
  138.         bar, press Return, use + (plus) to increase the size, use - 
  139.         (minus) to decrease the size, use Esc to put the size-selection
  140.         box away.
  141.  
  142.         Note:  the larger the window the more time XRAY will use during
  143.         its time slice.  If you are running a program which depends on
  144.         tight timing, I suggest you set the window to the minimum number
  145.         of lines you can get by with.
  146.  
  147.  
  148.     4.) Change Address
  149.  
  150.         This is how you change the location of the memory window.  The
  151.         default is 0040:0000 (SEGMENT:OFFSET), which happens to be the
  152.         ROM BIOS memory area on an IBM, and fully compatible, PC.  To
  153.         change this (note that the scroll feature also will change the
  154.         memory window display) position the selection bar and press
  155.         Return.  Now you can enter any hex digits for the new address,
  156.         can move to the desired digit to change or skip over digits
  157.         with the right and left arrows, can skip from segment to offset
  158.         or vice versa with the tab key, or end the edit by pressing
  159.         Return or the up arrow key.
  160.  
  161.     5.) Current Location
  162.  
  163.         This is the segment:offset address where control will return
  164.         when XRAY is done updating its display window.  This selection
  165.         is invoked and changed like the Set Scroll selection:  position
  166.         the selection bar and press Return, invoking a second smaller
  167.         window like:
  168.                 All
  169.                 None
  170.                 Mine
  171.  
  172.         All:  display all return addresses.
  173.         None: do not display any return addresses.
  174.         Mine: display only addresses that have the segment I enter.
  175.  
  176.         All is the default at load time, and will display every return
  177.         address on the stack.  None will cause XRAY to not update the
  178.         return address.  Mine will invoke a subordinate window where
  179.         you are allowed to enter the segment for the return addresses
  180.         you wish to see.  The return address is only updated if its
  181.         segment matches the one you've entered.
  182.  
  183.         Note:  this feature is useful if you suspect your program is
  184.         stuck in an endless loop, or to find what section of code is
  185.         getting executed the most.
  186.  
  187.         Like a large window size, when Current Location is enabled
  188.         XRAY will use more time during its time slice.  Disable (select
  189.         None) if you are running a time-critical program.
  190.  
  191.     6.) Unhook  XRAY
  192.  
  193.         This selection tells XRAY to unhook itself from the interrupt
  194.         vectors and deallocate the memory it occupies, thereby putting
  195.         the machine back to the state it was in before you loaded XRAY.
  196.  
  197.         To select, position the selection bar and press Return.
  198.  
  199.         WARNING:  do not Unhook XRAY while you are running another
  200.         program.  DOS maintains a free-memory linked list which gets
  201.         destroyed if XRAY is unhooked while another program has memory
  202.         allocated for itself.  If you want to see what I mean without
  203.         hurting anything do this:
  204.                 a.) Load XRAY
  205.                 b.) Run CHKDSK.COM and look at Free Memory Size
  206.                 c.) Run DEBUG.COM
  207.                 d.) Bring up the XRAY menu and Unhook XRAY
  208.                 e.) "Q"uit out of DEBUG.COM (if not already)
  209.                 f.) Run CHKDSK.COM and look at Free Mem Size
  210.                     (It will be different--alot smaller)
  211.                 g.) Reboot.
  212.  
  213.     Caveats:
  214.  
  215.         If you are using XRAY with other resident programs--like
  216.         Borland's Sidekick--I suggest you load XRAY after these other
  217.         programs.  XRAY filters certain interrupt vectors, but always
  218.         passes control on to the handler that was in the filtered vector
  219.         when XRAY loaded.  Some of these other resident programs do not
  220.         do that and thereby will hang XRAY.  I found, for instance, if
  221.         Sidekick is loaded first and XRAY second there are no problems.
  222.         If XRAY is loaded first and Sidekick second, Sidekick hangs XRAY
  223.         when the main menu is invoked--not very nice.
  224.  
  225.         Also, if you are going to Unhook XRAY, or unhook any other
  226.         resident program for that matter, make sure everything that
  227.         was loaded after the program to unhook has been unhooked.  For
  228.         instance, if you load Sidekick and then XRAY and then want to 
  229.         unhook Sidekick, first Unhook XRAY to keep the free-memory list
  230.         intact.
  231.  
  232.  
  233.  
  234.         Thank You for using XRAY.COM, the PC Background Monitor.
  235.         I hope XRAY is a pleasure for you to use.
  236.  
  237.  
  238.         John F. Ferguson II.
  239.